package com.langerra.shared.channel;

import java.io.Serializable;
import java.util.Collection;

import com.google.gwt.user.client.rpc.AsyncCallback;

public interface InputChannel<T extends Serializable>
		extends AbstractChannel {

	/**
	 * registers the parameter to be the sole incoming message receiver of this
	 * channel
	 * 
	 * this function is not implemented on server side yet and invocations will
	 * throw,
	 * 
	 * @param callback
	 *          the async call back to receive the incoming message
	 * @throws UnsupportedOperationException
	 *           when the factory call doesn't implement this interface (the
	 *           server side factory class)
	 * */
	void async(
			AsyncCallback<T> callback);

	/**
	 * @return the registered call back interface registered with invocation of {
	 *         {@link #async(AsyncCallback)}
	 * */
	AsyncCallback<T> async();

	/**
	 * read a message from the channel
	 * 
	 * @return the read message from the channel or null if non available
	 * */
	public T read();

	/**
	 * this method uses a 25 second timeout because of appengine timeout.
	 * 
	 * @return collection of all the read messages from the channel
	 * */
	public Collection<T> readAll();

	/**
	 * reads all of the messages available from the channel.
	 * 
	 * note that this interface is not designed to be blocking and if there is no
	 * message in the channel it will return an empty collection
	 * 
	 * @param timeout
	 *          maximum milliseconds to read already available messages within the
	 *          channel
	 * @return collection of all the read messages from the channel
	 * */
	public Collection<T> readAll(
			long timeout);
}
